od.1: add "raw" and "byte" to document description #1525
Conversation
|
I'm starting to notice a trend of apropos search-driven pull requests 😅 perhaps what we need is a smarter searching algorithm. I do not fully understand these concepts: What is a "raw octal"? |
Yes, that is one of my central goals, to increase manual accessibility, to increase appreciation for traditional BSD doc culture so that people keep investing in it. I am here, investing in it. We need technical writers thinking thoughtfully about the doc. That is why doc has it's own commit bits.
In the last 50 years many people have regressed on that hill, and we have seen astronomical documentation proliferation as a result. I like our simple algorithm. It scales down really well, really good at excluding incorrect information, and works really well if the Nd is written thoughtfully. Please, don't try to touch the apropos algorithm.
Alright, how do you feel about:
|
|
I may not be the most appropriate reviewer for this change, as my intention is not to sound too harsh: What is a "cooked"/"non-raw" byte? The way I understand it, it is already raw, so to speak? Regarding the "bytes", that would require a major change, indicating the number of bytes each representation has for each flag:
Maybe using the Open Group Specification as a guide (https://pubs.opengroup.org/onlinepubs/9799919799/utilities/od.html)? |
When it comes to doc, anyone who is sincere and interested is a good person. I show my drafts to completely unrelated people and ask them, "hey, we're trying to make some doc on an obscure engineering topic more clear, just reading this, what do you think this does? Does this seem clearer than this one?"
Rendered? "Raw" is a very common way of describing these types of outputs, look at endless questions on stack overflow, recent discussion on other reviews, etc. I don't understand your third paragraph. What do you mean? Although thinking about it, raw satisfies the search problem, and bytes is imprecise. |
For example: Current: With bytes: And so on. |
|
Damn, so bytes was perfectly accurate and helpful. I'll write it back in 3 hours when I get home. |
Many people recommend tools like xxd to do this in exactly the same way. Reinforce the culture of the BSD cathedral by increasing visibility of the base tooling that is portable, mature, well-documented, and equivelant in functionality. Also, tag spdx :) MFC after: 3 days
|
I can't seem to find a coherent sentence that includes both words that can be used in the description. |
|
Well then, unless you're objecting (which I respect and defend your right to do), this one will have to wait. I find it a solid compromise of coherence and visibility. "octal, decimal, hex, ASCII dump" is not a "coherent" sentence either, but it's quite an understandable "one line about what it does". You already said that calling it raw is not coherent, and byte is not coherent because it's two bytes sometimes. I do really appreciate the non-review comments and conscious thought on this though. |
Use case: User is looking for a tool to view raw bytes:
apropos -s1 rawapropos -s1 byteBoth do not show our excellent, mature tooling for this.
Proposition: They can be added cleanly and elegantly to the document description of od(1), and the resulting title still looks good even in MANWIDTH 59. Since this is a straightforward manual search bug fix for tooling in 14.2, I would like to humbly ask that this is MFC to the beta, that to increase the likelihood that the new generation of people who will starting in 14.2 have a greater chance of learning our culture.
Should I do the same for hd(1)?There isn't room to do this in hd(1) without line wrapping.